6장. CLAUDE.md 메모 파일 다루기 (입문판)

원서: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 5가지만 1. CLAUDE.md가 뭔지, 왜 있으면 편한지 설명한다. 2. CLAUDE.md에 어떻게 쓰는지, 무엇을 넣어야 하는지 구분한다. 3. CLAUDE.md 파일 3종류(프로젝트용/내 전용/모든 곳용)를 구분한다. 4. # 키로 즉석에서 메모 추가하고, 클로드 코드에게 관리를 맡기는 법을 따라 한다. 5. 클로드 코드가 CLAUDE.md를 어떻게 찾아 읽는지 설명한다.

학습 목표 이 장을 끝내면 CLAUDE.md가 무엇인지 설명할 수 있다. 세 종류의 CLAUDE.md 파일을 용도별로 구분할 수 있다.

키로 메모를 추가하는 절차를 따라 할 수 있다.

6.0 들어가기 전에 — 용어 한 줄 정리

이 장에 처음 나오는 말 몇 개만 미리 풀어두자. 모르는 단어가 본문에 또 나오면 여기로 돌아오면 된다.

CLAUDE.md 한 문장 뜻: 클로드 코드에게 "이 프로젝트는 이런 곳이야"라고 알려주는 메모 파일. 일상 비유: 새로 온 알바생 책상에 붙여두는 "우리 가게 안내문".

콘텍스트 윈도우(context window) 한 문장 뜻: 클로드 코드가 한 번에 읽고 기억할 수 있는 글의 최대 분량. 일상 비유: 한 번에 들 수 있는 장바구니 크기. 너무 많이 담으면 넘친다.

Stateless(상태 비저장) 한 문장 뜻: 대화가 끝나면 방금 한 이야기를 다음번엔 기억 못 하는 성질. 일상 비유: 매번 새 사람으로 출근하는 알바생. 어제 한 말을 오늘은 모른다.

루트 디렉터리(root directory) 한 문장 뜻: 폴더를 계속 상위로 거슬러 올라갔을 때 더는 올라갈 곳 없는 맨 위 폴더. 일상 비유: 건물의 1층 로비. 계단을 끝까지 내려가면 닿는 곳.

이 책의 "메모리"는 사람의 기억이 아니라 CLAUDE.md 같은 메모 파일을 가리킨다. "프로젝트 메모리 = 프로젝트용 메모 파일"이라고 읽으면 된다.

6.1 CLAUDE.md가 뭐길래?

이런 적 있죠?

새 대화를 켜서 클로드 코드에게 "버튼 하나 만들어줘"라고 했는데, 클로드 코드가 우리 프로젝트가 무슨 기술을 쓰는지 모르니 엉뚱한 방식으로 코드를 짠다. 그래서 매번 "우리는 React를 써", "테이블은 이 라이브러리로 만들어"를 처음부터 다시 설명한다. 다음 날 또 새 대화를 켜면? 또 처음부터 설명.

이 "매번 처음부터 설명" 문제를 없애주는 게 바로 CLAUDE.md다.

그게 바로 CLAUDE.md

CLAUDE.md는 프로젝트 폴더에 두는 안내 메모다. 클로드 코드는 일을 시작하기 전에 이 메모를 먼저 읽는다. 그래서 매번 설명하지 않아도, 클로드 코드가 "아, 이 프로젝트는 이렇구나" 하고 알아서 맞춰준다.

왜 매번 까먹을까 — Stateless 이야기

클로드 코드의 바탕이 되는 LLM은 Stateless하다. 앞서 6.0에서 본 대로, 매번 새 사람으로 출근하는 알바생과 같다. 어제 한 설명을 오늘은 기억 못 한다.

그래서 메모를 책상에 붙여둔다. 그게 CLAUDE.md다. 알바생이 매일 바뀌어도, 안내문은 책상에 그대로 붙어 있으니 늘 같은 안내를 받는다.

예시 — CLAUDE.md 맛보기

CLAUDE.md는 거창한 형식이 없다. 그냥 마크다운으로 또박또박 적으면 된다.

# 프로젝트 개요
이 프로젝트는 Next.js와 React로 만든 암호화폐 순위 대시보드입니다.
실시간 가격과 24시간 변동을 보여줍니다.

#으로 제목을 나누고, 아래에 평범한 말로 설명만 적어도 클로드 코드가 알아듣는다.

잘못된 예 vs 올바른 예 잘못된 예: CLAUDE.md 없이 매번 "우리 Next.js 써, React 써, 대시보드야…"를 새 대화마다 타이핑. 올바른 예: 위 메모를 CLAUDE.md에 한 번 적어두고, 다음부터는 바로 "순위 표 만들어줘"만 말한다.

이럴 때 이렇게: "왜 자꾸 같은 설명을 반복하지?" 싶으면, 그 반복 설명을 CLAUDE.md에 옮겨라. 그게 CLAUDE.md를 만드는 신호다.

여기까지 체크

CLAUDE.md는 프로젝트 폴더에 두는 마크다운 메모 파일이다. 클로드 코드는 작업 전에 이 메모를 읽고 맥락을 파악한다. LLM이 기억을 못 하는 Stateless 약점을, 책상에 붙인 안내문처럼 메워준다.

6.2 CLAUDE.md는 어떻게 적을까?

이런 적 있죠?

후배에게 "알아서 잘 해줘"라고 했더니, 내가 원한 것과 전혀 다른 결과가 나온 적 있을 거다. "알아서"는 사실 아무 정보도 안 준 것과 같다.

CLAUDE.md도 똑같다. 두루뭉술하게 적으면 클로드 코드도 헤맨다.

그게 바로 "명확한 지시"

CLAUDE.md를 잘 쓰는 비법은 화려한 형식이 아니라 명확한 지시다. 후배에게 일을 시킬 때처럼, 무엇을 어떻게 하라고 콕 집어 적으면 된다.

적는 요령

# 제목으로 섹션을 나눈다. 제목 아래에 평범한 말로 지시를 적는다. 꼭 지켜야 하는 규칙은 IMPORTANT나 YOU MUST 같은 말로 강조한다. 파일 구조나 설정 예시는 코드 블록으로 보여준다.

예시 — 기술과 구조를 콕 집기

# 사용할 기술
- 표를 만들 때는 꼭 tanstack table을 사용한다
- 폼을 만들 때는 꼭 tanstack form을 사용한다

# 프로젝트 구조
app/
├── (public)/   # 공개 페이지
├── admin/      # 관리자 페이지
└── api/        # API

이렇게 적어두면 클로드 코드가 어떤 라이브러리를 쓸지 헤매지 않고, 정해진 폴더 구조를 지켜준다.

잘못된 예 vs 올바른 예 잘못된 예: # 규칙 / 코드 잘 짜줘 — 무엇을 어떻게 할지 없음. 올바른 예: # 규칙 / IMPORTANT: 표는 반드시 tanstack table로 만든다 — 대상과 방법이 분명함.

이럴 때 이렇게: 클로드 코드가 자꾸 내가 안 쓰는 라이브러리로 코드를 짠다면, CLAUDE.md에 "이 프로젝트는 OO를 쓴다"를 강조해서 박아두면 된다.

여기까지 체크

# 제목으로 섹션을 나누고, 평범한 말로 지시를 적는다. IMPORTANT, YOU MUST로 강조하면 클로드 코드가 더 잘 지킨다. 라이브러리와 폴더 구조를 적어두면 결과 품질이 확 올라간다.

6.3 CLAUDE.md에 무엇을 넣을까?

이런 적 있죠?

좋다고 이것저것 다 적었더니 CLAUDE.md가 너무 길어졌다. 그런데 정작 클로드 코드는 더 헷갈려한다.

왜냐면 6.0에서 본 콘텍스트 윈도우, 즉 한 번에 읽을 수 있는 분량이 정해져 있기 때문이다.

그게 바로 "꼭 필요한 것만"

CLAUDE.md는 냉장고와 같다. 냉장고에 식재료를 다 욱여넣으면 문이 안 닫히고, 정작 자주 쓰는 재료를 못 찾는다. 자주 쓰는 것만 넣어야 요리가 빨라진다.

CLAUDE.md도 "매번 반복해서 설명하게 되는 것"만 넣는 게 핵심이다.

콘텍스트 윈도우의 구체 한계 수치(예: 200K 토큰)는 원서/노트 기준 예시이며, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인한다.

넣으면 좋은 항목 (앤트로픽 권장)

(bash 명령어란, 터미널에 입력해 컴퓨터에게 일을 시키는 명령 한 줄을 말한다. 마트 셀프 계산대에 바코드 찍는 것처럼 정해진 줄을 입력하는 것.)

예시 — 넣을 것 vs 뺄 것

잘못된 예: "2024년 1월에 시작했고 김OO, 이OO가 참여했다" — 추억담은 클로드 코드 작업에 안 쓰임. 올바른 예: "빌드는 npm run build, 테스트는 npm test" — 매번 쓰니 메모해두면 이득.

이럴 때 이렇게: 어떤 줄을 CLAUDE.md에 넣을지 고민될 때, "이걸 클로드 코드에게 또 설명한 적 있나?"를 떠올려라. 있으면 넣고, 없으면 빼라.

여기까지 체크

콘텍스트 윈도우는 유한하니 꼭 필요한 것만 넣는다. 쓸데없는 내용은 오히려 클로드 코드를 방해한다. "반복해서 설명하게 되는 것"이 CLAUDE.md 후보다.

6.4 CLAUDE.md 파일 3종류

이런 적 있죠?

"내 개인 API 키"를 CLAUDE.md에 적어 팀 저장소에 올렸다가, 키가 통째로 공개돼버린 사고. 반대로, 나만 쓰는 단축키 설정인데 모든 팀원에게 강제돼서 불편하게 만든 경우.

이건 "어디에 적을지"를 안 가렸기 때문이다. CLAUDE.md는 사실 용도별로 3종류가 있다.

그게 바로 파일 3종류

회사 규칙으로 비유하면 쉽다.

사용자 메모리(~/.claude/CLAUDE.md) = 내 개인 업무 습관. 어느 회사에 가도 적용되는 내 스타일. 예: "항상 2칸 들여쓰기."

프로젝트 메모리(./CLAUDE.md) = 이 팀의 공통 규칙. 이 프로젝트 사람 모두가 따른다. 예: "React 19 사용."

로컬 프로젝트 메모리(./claude.local.md) = 내 책상 위 포스트잇. 이 프로젝트와 관련 있지만 나만 보는 메모. 예: "내 테스트용 키, 내 샌드박스 주소."

여기서 ~는 홈 디렉터리(내 계정 폴더), .은 지금 작업 중인 프로젝트 폴더를 뜻하는 줄임 기호다. (샌드박스란, 실제 서비스에 영향 없이 마음껏 시험해보는 연습용 공간을 말한다.)

비교표

(.gitignore는 "이 파일은 Git에 올리지 마"라고 표시하는 목록 파일이다. 가방에 "이건 두고 가" 스티커를 붙이는 것과 비슷하다. — Git 기본은 4장에서 다뤘다.)

어디에 둘지 판단법

이 설정을 어디에 둘까?

프로젝트 전체 + 팀과 공유  → ./CLAUDE.md
이 프로젝트 + 나만 사용     → ./claude.local.md
모든 프로젝트 + 내 취향     → ~/.claude/CLAUDE.md

잘못된 예 vs 올바른 예 잘못된 예: 개인 API 키를 ./CLAUDE.md에 적고 커밋 → 키 유출. 올바른 예: 개인 API 키는 ./claude.local.md에 적고 .gitignore에 넣어 공유 차단.

이럴 때 이렇게: "이건 나만 알아야 하나, 팀도 알아야 하나, 모든 프로젝트에 필요한가?" 이 한 줄을 떠올리면 셋 중 어디에 둘지 정해진다.

여기까지 체크

팀과 공유할 규칙은 ./CLAUDE.md에 둔다. 개인 키·주소 같은 비밀은 ./claude.local.md에 두고 .gitignore에 넣는다. 모든 프로젝트에 적용할 내 취향은 ~/.claude/CLAUDE.md에 둔다.

6.5 CLAUDE.md 관리 노하우

이런 적 있죠?

CLAUDE.md를 처음 한 번 잘 써두고 몇 달을 방치했더니, 이미 안 쓰는 라이브러리 설명, 해결된 옛날 버그 기록이 잔뜩 남아 메모가 지저분해졌다.

정원을 한 번 심고 방치하면 잡초가 무성해지는 것과 같다. CLAUDE.md도 주기적으로 가꿔야 깔끔하고 쓸모 있다.

그게 바로 "꾸준한 관리"

관리 방법은 세 가지다. 아래에서 하나씩 따라 해보자.

방법 1 — # 키로 즉석 추가 (가장 자주 씀)

클로드 코드를 쓰다가 # 키를 누르고 지시를 적으면, 그 내용이 CLAUDE.md에 자동으로 들어간다. 손에서 일을 놓지 않고 바로 메모할 수 있어 편하다.

입력: # 변수 이름은 항상 카멜 케이스로 작성해 줘

→ 저장 위치를 묻는 화면:
  1. Project memory        → ./CLAUDE.md (커밋에 포함)
  2. Project memory (local)→ ./claude.local.md (.gitignore)
  3. User memory           → ~/.claude/CLAUDE.md (전역)

여기서 1·2·3을 고르는 기준은 방금 6.4에서 배운 그대로다.

팁: 팀과 나눌 규칙이면 1번을 골라 저장하고, 커밋에 포함시켜 팀원도 같은 혜택을 보게 한다.

방법 2 — 클로드에게 추천 맡기기 (안전한 길)

대화가 끝날 무렵, 클로드 코드에게 메모할 거리를 직접 골라달라고 부탁할 수 있다.

프롬프트 예시:
"지금까지의 대화를 기반으로 CLAUDE.md에 추가할 만한 내용을 추천해줘"

클로드 코드가 대화를 훑어 추가하면 좋을 항목을 제안한다. 내가 내용을 확인한 뒤 마음에 들면 반영하면 된다. 확인 없이 그대로 다 넣지는 말자.

방법 3 — 정리 요청하기

CLAUDE.md가 너무 커지면, 클로드 코드에게 정리를 부탁한다.

프롬프트 예시:
"CLAUDE.md가 너무 커지고 있어. 프로젝트를 다시 이해하고,
필요 없는 내용은 삭제하고 과도한 내용은 줄여줘. 수정안을 추천해줘."

그러면 간소화된 CLAUDE.md를 제안받는다.

한 걸음 더 ▸ 강조 표현의 힘과 /compact

/compact는 대화가 길어졌을 때 클로드 코드가 지금까지의 내용을 짧게 압축하는 명령이다. 압축을 하면 자잘한 내용은 사라질 수 있는데, 이때 IMPORTANT·YOU MUST로 강조해 둔 규칙은 살아남을 가능성이 높다.

일반 지시:  "변수명은 카멜 케이스로 작성하세요"
강조 지시:  "IMPORTANT: 변수명은 반드시 카멜 케이스로 작성합니다"

꼭 지켜야 할 규칙일수록 강조해서 적어두면, 압축 후에도 지시가 끝까지 남는다.

잘못된 예 vs 올바른 예 잘못된 예: 추억담·해결된 버그·옛 라이브러리 변경 이력을 CLAUDE.md에 계속 쌓아둠. 올바른 예: 현재 상태만 남기고 과거 이력은 지움. 꼭 지킬 규칙엔 IMPORTANT를 붙임.

이럴 때 이렇게: 메모가 5화면을 넘어가게 길어졌다면, 방법 3으로 클로드 코드에게 정리를 맡기고 추천안을 검토해 반영한다.

여기까지 체크

# 키로 작업 중 즉시 메모를 추가할 수 있다. 대화 끝에 클로드에게 추가 추천을 부탁하면 편하다. 메모가 커지면 클로드에게 정리를 맡긴다. IMPORTANT·YOU MUST 강조는 /compact 후에도 규칙이 살아남게 돕는다.

6.6 클로드 코드는 CLAUDE.md를 어떻게 찾아 읽을까?

이런 적 있죠?

웹 프로젝트와 모바일 프로젝트가 한 회사 폴더 안에 같이 있다. 둘 다 똑같은 "한국어 docstring 작성" 규칙을 쓰는데, 이걸 양쪽 CLAUDE.md에 똑같이 두 번 적자니 번거롭다. 한쪽만 고치면 둘이 어긋난다.

이 번거로움을, 클로드 코드의 읽기 방식이 자연스럽게 풀어준다.

그게 바로 "위로 거슬러 읽기"

클로드 코드는 지금 작업 중인 폴더에서 시작해, 상위 폴더로 계속 거슬러 올라가며 만나는 CLAUDE.md를 전부 읽는다. 루트(맨 위 폴더)에 닿을 때까지 올라간다.

엘리베이터로 비유하면, 지금 층의 안내문을 읽고, 한 층씩 내려가며 각 층 안내문도 모두 읽고, 1층 로비까지 내려가는 셈이다.

예시 — 공통 규칙 한 번만 적기

/abc/
├── CLAUDE.md        ← 공통 규칙 (웹 + 모바일 둘 다)
├── web/
│   └── CLAUDE.md    ← 웹 전용 규칙
└── mobile/
    └── CLAUDE.md    ← 모바일 전용 규칙

/abc/web에서 클로드 코드를 실행하면, /abc/web/CLAUDE.md와 위쪽 /abc/CLAUDE.md를 둘 다 읽는다. 그래서 공통 규칙은 위 폴더에 한 번만 적어두고, 각 프로젝트의 고유 규칙만 자기 폴더에 적으면 된다.

(이렇게 여러 작은 프로젝트를 한 큰 폴더에 모아두는 방식을 모노레포라고 부른다. 한 건물에 여러 가게가 입주한 상가와 비슷하다.)

잘못된 예 vs 올바른 예 잘못된 예: 공통 규칙을 web과 mobile 양쪽에 똑같이 복사 → 한쪽만 고쳐 둘이 어긋남. 올바른 예: 공통 규칙은 상위 /abc/CLAUDE.md에 한 번만 적고, 전용 규칙만 각자 폴더에 둠.

이럴 때 이렇게: 여러 프로젝트가 같은 회사 규칙을 공유한다면, 그 규칙을 공통 상위 폴더 CLAUDE.md로 올려라. 위로 거슬러 읽기 덕분에 모든 하위 프로젝트가 자동으로 그 규칙을 받는다.

여기까지 체크

클로드 코드는 작업 폴더에서 루트까지 거슬러 올라가며 모든 CLAUDE.md를 읽는다. 이 덕분에 공통 규칙과 개별 규칙을 분리해 관리할 수 있다. 연관된 여러 프로젝트가 상위 폴더의 CLAUDE.md를 함께 공유할 수 있다.

직접 해보기 (연습 문제)

문제 1 — CLAUDE.md 써보기

다음 조건의 프로젝트에 맞는 CLAUDE.md를 직접 적어보자. - Next.js + TypeScript 프로젝트 - Tailwind CSS 사용 - Jest로 테스트

# 프로젝트 개요
Next.js와 TypeScript로 만든 웹 애플리케이션입니다.

# 기술 스택
- 언어: TypeScript
- 스타일: Tailwind CSS
- 테스트: Jest

# 코딩 규칙
- IMPORTANT: 모든 컴포넌트는 TypeScript로 작성
- 변수명은 카멜 케이스

# 자주 쓰는 명령어
- 빌드: `npm run build`
- 테스트: `npm test`

문제 2 — 어느 파일에 둘까?

아래 설정을 각각 어느 CLAUDE.md에 둘지 골라보자. 1. "이 프로젝트는 Python과 FastAPI를 쓴다" 2. "내 개인 샌드박스 주소는 https://my-sandbox.dev 다" 3. "나는 모든 프로젝트에서 2칸 들여쓰기를 선호한다" 4. "내 로컬 테스트용 API 키는 sk-test-1234 다"

문제 3 — 정리해보기

아래 CLAUDE.md는 과거 이력으로 너무 길다. 현재 상태만 남기고 줄여보자.

# 프로젝트
2024년에 시작했고 여러 명이 참여했습니다.
React 17을 쓰다가 18로, 지금은 19입니다.
CSS는 styled-components를 쓰다 Tailwind로 바꿨습니다.
DB는 MySQL에서 PostgreSQL로 옮겼습니다.

# 기술 스택
- 프론트엔드: React 19 + Tailwind CSS
- 데이터베이스: PostgreSQL

이 장 한눈에 정리

CLAUDE.md는 프로젝트 폴더에 두는 안내 메모로, 클로드 코드가 작업 전에 읽는다. # 제목 + 명확한 지시 + IMPORTANT/YOU MUST 강조로 적는다. 콘텍스트 윈도우가 유한하니 반복 설명할 핵심만 넣는다. 파일은 3종류 — 프로젝트(./CLAUDE.md), 로컬(./claude.local.md), 사용자(~/.claude/CLAUDE.md). # 키로 즉석 추가하고, 클로드에게 추천·정리를 맡겨 관리한다. 클로드 코드는 작업 폴더에서 루트까지 거슬러 올라가며 모든 CLAUDE.md를 읽는다.

더 알아보기

다음 장 예고: 다음 장에서는 클로드 코드를 더 깊이 다루는 주제로 이어진다. 지금 몰라도 이 장을 이해하는 데 전혀 문제없다.